docs: improve S2 docs markdown / agent skill by reidbarber · Pull Request #9939 · adobe/react-spectrum

reidbarber · 2026-04-16T22:00:28Z

Includes improvements to the markdown docs output and S2 agent skill. Also adds a comment to PRs to show the diff in the agent skills.

Markdown output improvements:

skip redirect pages (the mcp.mdx pages got replaced by the ai.mdx pages)
skip error pages (no need for errror.md files)
fix inline code being stripped from page descriptions (visible here)
include Routers section in S2 getting-started.md (renders at bottom of the page once and gets referenced above)
improve style-macro.md (more clear and concise, uses aliases for repetitive sets)

Skill Improvements:

fix heading levels in component-decision-tree.md
improve illustration example in implementation-guidance.md to include all three types of illustrations
improve skill with guidance for using Buttons with icons + text (ensure text is wrapped in Text)
improve skill with guidance to avoid concatenating class names from the style macro
add a figma-to-s2.md resource to help with implementing designs with the Figma MCP
add a creating-custom-components.md resource for showing RAC + style macro usage

General docs improvements:

add 'dnd' tag for RAC dnd docs page (so it shows up if you search 'dnd' in the docs)
mention passing isFocusVisible in JSDoc for focusRing

✅ Pull Request Checklist:

Included link to corresponding React Spectrum GitHub Issue.
Added/updated unit tests and storybook for this change (for new code or code which already has tests).
Filled out test instructions.
Updated documentation (if it already exists for this component).
Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

View markdown docs output and skill output for affected files.

To see the agent skill diff, first make sure you have the latest release's skill installed:

npx skills add https://react-spectrum.adobe.com --skill react-spectrum-s2

then install this PR's and look at the diff:

npx skills add https://d1pzu54gtk2aed.cloudfront.net/pr/91dfb8d78bbe5b9a0a3b1bd48f8ff9fc784c023c/ --skill react-spectrum-s2

🧢 Your Project:

…he style macro

* add skill differ * improve comment * deploy full diff + link to new/changed files * fix path * remove full diff output * comment with install links

rspbot · 2026-04-20T18:28:39Z

Build successful! 🎉

rspbot · 2026-05-11T15:58:09Z

Build successful! 🎉

# Conflicts: # packages/dev/s2-docs/scripts/generateMarkdownDocs.mjs

rspbot · 2026-05-14T16:40:26Z

Build successful! 🎉

rspbot · 2026-05-14T19:40:44Z

Build successful! 🎉

rspbot · 2026-05-14T23:08:09Z

Build successful! 🎉

rspbot · 2026-05-14T23:16:33Z

Build successful! 🎉

rspbot · 2026-05-14T23:16:35Z

Agent Skills Changes

Added (2)

s2/skills/react-spectrum-s2/references/guides/creating-custom-components.md $\color{green}{+353}$
s2/skills/react-spectrum-s2/references/guides/figma-to-s2.md $\color{green}{+139}$

Removed (2)

react-aria/skills/react-aria/references/components/mcp.md
s2/skills/react-spectrum-s2/references/components/mcp.md

Modified (70)

react-aria/skills/index.json $\color{red}{-1}$
react-aria/skills/react-aria/SKILL.md $\color{green}{+2}$ $\color{red}{-3}$
react-aria/skills/react-aria/references/components/Form.md $\color{green}{+3}$ $\color{red}{-1}$
react-aria/skills/react-aria/references/components/ListBox.md $\color{green}{+2}$ $\color{red}{-2}$
react-aria/skills/react-aria/references/components/Menu.md $\color{green}{+4}$ $\color{red}{-4}$
react-aria/skills/react-aria/references/components/Toast.md $\color{green}{+1}$ $\color{red}{-1}$
react-aria/skills/react-aria/references/guides/forms.md $\color{green}{+3}$ $\color{red}{-1}$
react-aria/skills/react-aria/references/guides/quality.md $\color{green}{+1}$ $\color{red}{-1}$
react-aria/skills/react-aria/references/guides/selection.md $\color{green}{+5}$ $\color{red}{-5}$
react-aria/skills/react-aria/references/internationalized/date/CalendarDate.md $\color{green}{+1}$ $\color{red}{-1}$
react-aria/skills/react-aria/references/internationalized/date/CalendarDateTime.md $\color{green}{+1}$ $\color{red}{-1}$
react-aria/skills/react-aria/references/internationalized/date/ZonedDateTime.md $\color{green}{+1}$ $\color{red}{-1}$
react-aria/skills/react-aria/references/llms.txt $\color{green}{+6}$ $\color{red}{-8}$
react-aria/skills/react-aria/references/utilities/useField.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/index.json $\color{green}{+2}$ $\color{red}{-1}$
s2/skills/migrate-react-spectrum-v3-to-s2/references/docs-getting-started.md $\color{green}{+111}$ $\color{red}{-5}$
s2/skills/migrate-react-spectrum-v3-to-s2/references/docs-style-macro.md $\color{green}{+118}$ $\color{red}{-190}$
s2/skills/migrate-react-spectrum-v3-to-s2/references/docs-styling.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/SKILL.md $\color{green}{+298}$ $\color{red}{-72}$
s2/skills/react-spectrum-s2/references/components/ActionBar.md $\color{green}{+5}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/ActionButton.md $\color{green}{+3}$ $\color{red}{-3}$
s2/skills/react-spectrum-s2/references/components/ActionButtonGroup.md $\color{green}{+2}$ $\color{red}{-2}$
s2/skills/react-spectrum-s2/references/components/ActionMenu.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/AvatarGroup.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/Button.md $\color{green}{+5}$ $\color{red}{-5}$
s2/skills/react-spectrum-s2/references/components/ButtonGroup.md $\color{green}{+2}$ $\color{red}{-2}$
s2/skills/react-spectrum-s2/references/components/Calendar.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/Card.md $\color{green}{+7}$ $\color{red}{-5}$
s2/skills/react-spectrum-s2/references/components/CardView.md $\color{green}{+2}$ $\color{red}{-2}$
s2/skills/react-spectrum-s2/references/components/ColorSwatch.md $\color{green}{+2}$ $\color{red}{-2}$
s2/skills/react-spectrum-s2/references/components/ColorSwatchPicker.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/ComboBox.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/DateField.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/DatePicker.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/DateRangePicker.md $\color{green}{+2}$ $\color{red}{-2}$
s2/skills/react-spectrum-s2/references/components/Dialog.md $\color{green}{+6}$ $\color{red}{-6}$
s2/skills/react-spectrum-s2/references/components/Divider.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/Form.md $\color{green}{+7}$ $\color{red}{-5}$
s2/skills/react-spectrum-s2/references/components/Image.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/InlineAlert.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/Link.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/LinkButton.md $\color{green}{+3}$ $\color{red}{-3}$
s2/skills/react-spectrum-s2/references/components/ListView.md $\color{green}{+2}$ $\color{red}{-2}$
s2/skills/react-spectrum-s2/references/components/Menu.md $\color{green}{+3}$ $\color{red}{-3}$
s2/skills/react-spectrum-s2/references/components/Meter.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/Picker.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/ProgressBar.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/ProgressCircle.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/RangeCalendar.md $\color{green}{+2}$ $\color{red}{-2}$
s2/skills/react-spectrum-s2/references/components/SearchField.md $\color{green}{+5}$ $\color{red}{-5}$
s2/skills/react-spectrum-s2/references/components/SegmentedControl.md $\color{green}{+3}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/SelectBoxGroup.md $\color{green}{+3}$ $\color{red}{-3}$
s2/skills/react-spectrum-s2/references/components/StatusLight.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/TableView.md $\color{green}{+7}$ $\color{red}{-7}$
s2/skills/react-spectrum-s2/references/components/Tabs.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/TagGroup.md $\color{green}{+8}$ $\color{red}{-4}$
s2/skills/react-spectrum-s2/references/components/TextArea.md $\color{green}{+2}$ $\color{red}{-2}$
s2/skills/react-spectrum-s2/references/components/TimeField.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/ToggleButton.md $\color{green}{+3}$ $\color{red}{-3}$
s2/skills/react-spectrum-s2/references/components/ToggleButtonGroup.md $\color{green}{+2}$ $\color{red}{-2}$
s2/skills/react-spectrum-s2/references/components/Tooltip.md $\color{green}{+2}$ $\color{red}{-2}$
s2/skills/react-spectrum-s2/references/components/TreeView.md $\color{green}{+2}$ $\color{red}{-2}$
s2/skills/react-spectrum-s2/references/components/icons.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/components/illustrations.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/guides/component-decision-tree.md $\color{green}{+30}$ $\color{red}{-12}$
s2/skills/react-spectrum-s2/references/guides/forms.md $\color{green}{+3}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/guides/getting-started.md $\color{green}{+111}$ $\color{red}{-5}$
s2/skills/react-spectrum-s2/references/guides/style-macro.md $\color{green}{+118}$ $\color{red}{-190}$
s2/skills/react-spectrum-s2/references/guides/styling.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/llms.txt $\color{green}{+3}$ $\color{red}{-5}$

Install

React Spectrum S2:

npx skills add https://d1pzu54gtk2aed.cloudfront.net/pr/91dfb8d78bbe5b9a0a3b1bd48f8ff9fc784c023c/

React Aria:

npx skills add https://d5iwopk28bdhl.cloudfront.net/pr/91dfb8d78bbe5b9a0a3b1bd48f8ff9fc784c023c/

LFDanLu

LGTM, did we want to add the skeleton collection reference anywhere here or maybe not applicable until it is more widely supported?

reidbarber · 2026-05-15T22:21:48Z

@LFDanLu Yeah felt weird to mention since it is just for CardView now. I'll make a note to include it in a future update.

reidbarber added 11 commits April 15, 2026 17:47

fix headings levels in component decision tree

e211797

better illustration examples in SKILL.md

4a4e7c1

skip redirects in markdown output

b9f837e

fix stripped inline code from page descriptions in markdown output

5beabc0

fix S2 Routers rendering in markdown output

c6572c4

add dnd tag for RAC dnd docs page

56422c5

improve Style Macro docs page markdown output

4212bd5

remove error pages from output

9c78fcb

better JSDoc for focusRing (mention passing isFocusVisible)

e4bac2f

improve skill with guidance on Buttons with icons and text

41694ef

improve skill with guidance to avoid concatenating class names from t…

91cb93c

…he style macro

github-actions Bot added the S2 label Apr 16, 2026

reidbarber added 2 commits April 20, 2026 13:20

testing skill differ (#9947)

d1a3a62

* add skill differ * improve comment * deploy full diff + link to new/changed files * fix path * remove full diff output * comment with install links

Merge branch 'main' into s2-skill-fixes

ccdf1c9

reidbarber added 2 commits May 11, 2026 10:45

Merge remote-tracking branch 'origin/main' into s2-skill-fixes

33408ec

format

46ca23c

devongovett previously approved these changes May 11, 2026

View reviewed changes

Merge remote-tracking branch 'origin/main' into s2-skill-fixes

f50e586

# Conflicts: # packages/dev/s2-docs/scripts/generateMarkdownDocs.mjs

reidbarber dismissed devongovett’s stale review via f50e586 May 13, 2026 16:29

reidbarber added 3 commits May 13, 2026 12:43

fix formatting

5403166

skill improvements

d1c90fb

more skill improvements

3363135

reidbarber added release ready for review labels May 14, 2026

add figma-to-s2 resource

753bd92

add creating-custom-components.md reference

41e3f4e

reidbarber added 2 commits May 14, 2026 18:07

reference new creating-custom-components.md elsewhere

fd46a80

Merge remote-tracking branch 'origin/main' into s2-skill-fixes

91dfb8d

yihuiliao approved these changes May 15, 2026

View reviewed changes

LFDanLu approved these changes May 15, 2026

View reviewed changes

reidbarber added this pull request to the merge queue May 15, 2026

Merged via the queue into main with commit 6d4afb9 May 15, 2026
33 checks passed

reidbarber deleted the s2-skill-fixes branch May 15, 2026 22:31

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: improve S2 docs markdown / agent skill#9939

docs: improve S2 docs markdown / agent skill#9939
reidbarber merged 23 commits into
mainfrom
s2-skill-fixes

reidbarber commented Apr 16, 2026 •

edited

Loading

Uh oh!

rspbot commented Apr 20, 2026

Uh oh!

rspbot commented May 11, 2026

Uh oh!

rspbot commented May 14, 2026

Uh oh!

rspbot commented May 14, 2026

Uh oh!

rspbot commented May 14, 2026

Uh oh!

rspbot commented May 14, 2026

Uh oh!

rspbot commented May 14, 2026

Uh oh!

LFDanLu left a comment

Uh oh!

reidbarber commented May 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

reidbarber commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull Request Checklist:

📝 Test Instructions:

🧢 Your Project:

Uh oh!

rspbot commented Apr 20, 2026

Uh oh!

rspbot commented May 11, 2026

Uh oh!

rspbot commented May 14, 2026

Uh oh!

rspbot commented May 14, 2026

Uh oh!

rspbot commented May 14, 2026

Uh oh!

rspbot commented May 14, 2026

Uh oh!

rspbot commented May 14, 2026

Agent Skills Changes

Uh oh!

LFDanLu left a comment

Choose a reason for hiding this comment

Uh oh!

reidbarber commented May 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

reidbarber commented Apr 16, 2026 •

edited

Loading